home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 May: Tool Chest / Developer CD Series May 1996 (Tool Chest) (Apple Computer) (1996).iso / Sample Code / Snippets / QuickDraw / Restore Screen Cluts / EmergMem.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-01-18  |  8.6 KB  |  198 lines  |  [TEXT/MPS ]
  1. #ifndef __EMERGMEM__
  2. #define __EMERGMEM__
  3. /******************************************************************************\
  4. *
  5. * Apple Macintosh Developer Technical Support
  6. *
  7. * Header file for the emergency memory routines
  8. *
  9. * Program: ColorReset
  10. * File:    EmergMem.h
  11. *
  12. * by:      Forrest Tanaka
  13. *
  14. * Copyright © 1988-1991 Apple Computer, Inc.
  15. * All rights reserved.
  16. *
  17. * ------------------------------------------------------------------------------
  18. *
  19. * EmergMem contains routines to handle emergency memory situations.  This is
  20. * used for Toolbox routines that either don’t check for memory-full errors, or
  21. * that call _SysErr when they can’t allocate the memory that they need.  The
  22. * purpose of the routines in this file is to make sure that these toolbox
  23. * routines always have the memory they need.
  24. *
  25. \******************************************************************************/
  26.     
  27.  
  28. /******************************************************************************\
  29. * Header Files
  30. \******************************************************************************/
  31.  
  32. #include <Types.h>
  33. #include <Memory.h>
  34.  
  35.  
  36. /******************************************************************************\
  37. * Constants
  38. \******************************************************************************/
  39.  
  40. #define kAllocApp true /* For NewPtrMargin/NewHandleMargin for app heap alloc */
  41. #define kAllocClr true /* For NewPtrMargin/NewHandleMargin to clear mem block */
  42.  
  43.  
  44. /******************************************************************************\
  45. * InstallAppGZ - Installs the application grow zone proc
  46. *
  47. * This routine is called whenever this application’s simple grow-zone procedure
  48. * (see EmergMem.c for the source for the grow-zone procedure) is to be
  49. * installed.  From this point on, any requests for memory by this application or
  50. * the system invoke our grow-zone procedure if there isn’t enough memory to
  51. * satisfy the request.
  52. \******************************************************************************/
  53.  
  54. void InstallAppGZ(void);
  55.  
  56.  
  57. /******************************************************************************\
  58. * DeinstallAppGZ - install the application grow zone proc
  59. *
  60. * This routine is called whenever this application’s simple grow-zone procedure
  61. * (see EmergMem.c for the source for the grow-zone procedure) is to be
  62. * deinstalled.  From this point on, any requests for memory by this application
  63. * or the system return memFullErr if there isn’t enough memory to satisfy the
  64. * request.
  65. \******************************************************************************/
  66.  
  67. void DeinstallAppGZ(void);
  68.  
  69.  
  70. /******************************************************************************\
  71. * InitEmergMem - Allocate emergency memory
  72. *
  73. * This is called at startup time to allocate the emergency memory block that can
  74. * be deallocated by the grow zone procedure (this application’s grow-zone
  75. * procedure is defined privately in EmergMem.c).  InitEmergMem also installs
  76. * this application’s grow-zone proc.
  77. *
  78. * If there isn’t enough memory to allocate the block of emergency memory, then
  79. * a subsequent call to FailLowMemory(0) returns TRUE.
  80. \******************************************************************************/
  81.  
  82. void InitEmergMem(void);
  83.  
  84.  
  85. /******************************************************************************\
  86. * RecoverEmergMem - Recover emergency memory
  87. *
  88. * This is called from the event loop if NoEmergMem indicates that the emergency
  89. * memory was deallocated by this application’s grow-zone procedure.  This
  90. * routine will attempt recover the emergency memory.  If this fails, then some
  91. * application options and commands are disabled until there is enough free
  92. * memory to enable them again.
  93. \******************************************************************************/
  94.  
  95. void RecoverEmergMem(void);
  96.  
  97.  
  98. /******************************************************************************\
  99. * FailLowMemory - Is there enough free space in heap to allocate memory?
  100. *
  101. * FailLowMemory is called any time a potentially significant amount of non-
  102. * temporary memory is about to be allocated.  It returns true if there’s enough
  103. * free space in the heap to allocate the requested amount of memory and still
  104. * have a significant amount of free space left over, and if the emergency memory
  105. * isn’t being used.  See EmergMem.c for the definition of “significant amount.”
  106. * "memRequest" specifies the number of bytes that are about to be allocated.
  107. *
  108. * This routine is also used even if the exact amount of memory about to be
  109. * allocated isn’t known.  In this case, zero is passed in memRequest.  If
  110. * FailLowMemory returns true, then there’s enough memory for the the emergency
  111. * memory and a significant amount of free memory.  If FailLowMemory returns
  112. * false, then either there isn’t a significant amount of free memory, or if the
  113. * emergency memory was deallocated by this application’s grow-zone procedure, or
  114. * both.  This is actually the usual way that I use this function, because I
  115. * normally use it for calls to the Toolbox, and there’s usually no reliable way
  116. * to determine how much memory the Toolbox is going to allocate.
  117. \******************************************************************************/
  118.  
  119. Boolean FailLowMemory(
  120.     long memRequest);
  121.  
  122.  
  123. /******************************************************************************\
  124. * NoEmergMem - Check to see if emergency memory is being used or not
  125. *
  126. * Before my application attempts to use more memory, I call this routine to
  127. * check if I'm already using my emergency memory.  If so, then I’d better
  128. * prepare to die or get my emergency memory back.
  129. \******************************************************************************/
  130.  
  131. Boolean NoEmergMem(void);
  132.  
  133.  
  134. /******************************************************************************\
  135. * NewHandleMargin - Create a new handle without using emergency memory
  136. *
  137. * Many toolbox routines simply call SysErr when they run out of memory.  That’s
  138. * not too cool, so I try to make certain that the memory they need is always
  139. * available by making sure that I never request so much memory that the toolbox
  140. * routines are in danger of running out of memory and calling SysErr.  This is
  141. * achieved by calling NewHandleMargin instead of NewHandle any time a
  142. * relocatable memory block is desired.  NewHandle returns memFullErr in MemErr
  143. * if there isn’t enough free contiguous space to satisfy the request.
  144. * NewHandleMargin returns nil if there isn’t enough memory to allocate a block
  145. * of the size specified by "requestedSize".
  146. *
  147. *     WARNING: Don’t depend on MemError after calling NewHandleMargin.  The
  148. *     only way to tell whether it succeeded or not is to compare the result
  149. *     against NIL.
  150. *
  151. * If "appHeapAlloc" is kAppHeap, then the block of memory is allocated in the
  152. * application’s heap.  If "appHeapAlloc" is !kAppHeap, then the block of
  153. * memory is allocated in the system heap.
  154. *
  155. * If "clearMem" is kAllocClr, then all the bytes in the block of memory are
  156. * cleared to zero.  If !kAllocClr is passed, then none of the bytes in the
  157. * block of memory are touched after being allocated.
  158. \******************************************************************************/
  159.  
  160. Handle NewHandleMargin(
  161.     Size    requestedSize,
  162.     Boolean appHeapAlloc,
  163.     Boolean clearMem);
  164.  
  165.  
  166. /******************************************************************************\
  167. * NewPtrMargin - Create a new pointer without using emergency memory
  168. *
  169. * Many toolbox routines simply call SysErr when they run out of memory.  That’s
  170. * not too cool, so I try to make certain that the memory they need is always
  171. * available by making sure that I never request so much memory that the toolbox
  172. * routines are in danger of running out of memory and calling SysErr.  This is
  173. * achieved by calling NewPtrMargin instead of NewPtr any time a non-relocatable
  174. * memory block is desired.  NewPtr returns memFullErr in MemErr if there isn’t
  175. * enough free contiguous space to satisfy the request.  NewPtrMargin returns nil
  176. * if there isn’t enough memory to allocated a block of the size specified by
  177. * "requestedSize".
  178. *
  179. *     WARNING: Don’t depend on MemError after calling NewPtrMargin.  The
  180. *     only way to tell whether it succeeded or not is to compare the result
  181. *     against NIL.
  182. *
  183. * If "appHeapAlloc" is kAppHeap, then the block of memory is allocated in the
  184. * application’s heap.  If "appHeapAlloc" is !kAppHeap, then the block of
  185. * memory is allocated in the system heap.
  186. *
  187. * If "clearMem" is kAllocClr, then all the bytes in the block of memory are
  188. * cleared to zero.  If !kAllocClr is passed, then none of the bytes in the
  189. * block of memory are touched after being allocated.
  190. \******************************************************************************/
  191.  
  192. Ptr NewPtrMargin(
  193.     Size    requestedSize,
  194.     Boolean appHeapAlloc,
  195.     Boolean clearMem);
  196.  
  197.  
  198. #endif